<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>User Guide</title>
<link href="tabs.css" rel="stylesheet" type="text/css" />
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="alias.css" rel="stylesheet" type="text/css" />
<script type="text/javascript" src="alias.js"></script>

<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>



<script type="text/javascript">
  jQuery(document).ready(function () {
    if(gref){ // Number all _img and _table classes
      gref();
    }
  });
</script>

</head>
<body>
<div id="top"><!-- do not remove this div! -->

<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  
  
  <td style="padding-left: 0.5em;">
   <div id="projectname">nRF Gazell
   &#160;<span id="projectnumber">version 0.4.2</span>
   </div>
   
  </td>
  
  
  
 </tr>
 </tbody>
</table>
</div>

<!-- Generated by Doxygen 1.7.5 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="modules.html"><span>Modules</span></a></li>
      <li><a href="annotated.html"><span>Data&#160;Structures</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
    </ul>
  </div>
</div>
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
  initNavTree('group__gzp__02__user__guide.html','');
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">User Guide</div>  </div>
<div class="ingroups"><a class="el" href="group__modules__02__gzp.html">Gazell Pairing</a></div></div>
<div class="contents">
<p>The Gazell Pairing library for the nRF51 enables applications to use the Gazell Link Layer to provide a secure wireless link between Gazell nodes. The library is customized for pairing a nRF51 Gazell Device (e.g. a mouse, keyboard or remote control) with a Gazell Host (typically a USB dongle).</p>
<p>The Gazell Pairing library has the following features:</p>
<ul>
<li>Close proximity pairing</li>
<li>AES-128 encryption</li>
<li>Secure key exchange</li>
<li>Dynamic update of key during runtime</li>
<li>Storage of pairing parameters in non volatile memory</li>
<li>One time programmable (OTP) device compatibility</li>
</ul>
<p>Secure key exchange in Gazell Pairing is based on a Secret Key which is factory programmed. Only nodes that share the same Secret Key, i.e. for a desktop ecosystem, can form an encrypted link. After a pair of nodes have authenticated each other's Secret Key, the Gazell Host generates a random key termed the "Host ID". This is encrypted with the Secret Key and sent to the Gazell Device. This Host ID key is used to transmit a Dynamic Key which is used for encrypting subsequent data.</p>
<p>All encrypted exchanges of keys and data use a session token, which is equivalent to AES counter mode and provides protection against ciphertext attacks. In addition, all encrypted packets include an encrypted packet validation ID in order that all packets are authenticated.</p>
<p>The security features of Gazell provide counter measures against a range of potential attacks, including:</p>
<ul>
<li>Frequency analysis attacks</li>
<li>"Hostile" Device attacks</li>
<li>Known-plaintext attacks</li>
<li>Man-in-the-middle attacks</li>
<li>Passive eavesdropping</li>
<li>Replay attacks</li>
</ul>
<h2><a class="anchor" id="Contents"></a>
Contents</h2>
<ul>
<li><a class="el" href="group__gzp__02__user__guide.html#gzpair_proximity">Close Proximity Pairing</a></li>
<li><a class="el" href="group__gzp__02__user__guide.html#key_ex_stages">Pairing and key exchange stages</a><ul>
<li><a class="el" href="group__gzp__02__user__guide.html#factory_pres">Factory preset parameters</a></li>
<li><a class="el" href="group__gzp__02__user__guide.html#address_exchange">System Address exchange</a></li>
<li><a class="el" href="group__gzp__02__user__guide.html#host_id_exchange">Host ID exchange</a></li>
<li><a class="el" href="group__gzp__02__user__guide.html#dyn_key_exchange">Dynamic Key exchange</a></li>
</ul>
</li>
<li><a class="el" href="group__gzp__02__user__guide.html#enc_data_exchange">Encrypted User Data exchange</a></li>
<li><a class="el" href="group__gzp__02__user__guide.html#gzll_limitations">Resource Requirements</a></li>
<li><a class="el" href="group__gzp__02__user__guide.html#terminology">Terminology</a></li>
</ul>
<p>The following explains the function of the key exchange sequences that are required to exchange encrypted data.</p>
<h2><a class="anchor" id="gzpair_proximity"></a>
Close Proximity Pairing</h2>
<p>A feature of Gazell Pairing is to only allow pairing when Host and Device are in close proximity of each other. The carrier detect functionality on the Host side of the nRF24L01+/nRF24LE1/nRF24LU1+ is employed so that only Devices residing close (&lt;30cm) to the Host will be allowed to pair. Proximity estimation is essential to avoid confusion when pairing in certain environments, for example in an office.</p>
<p>When requesting a System Address, the Device sets the TX power to a low level as set by GZP_POWER. By measuring the receive signal strength when a pairing request is received from a Device, the Host is able to estimate the relative proximity of the requesting Device.</p>
<div class="image">
<img src="pairing_block.png" alt="pairing_block.png"/>
<div class="caption">
Pairing concept</div></div>
 <h2><a class="anchor" id="key_ex_stages"></a>
Pairing and key exchange stages</h2>
<p>The pairing and key exchange process consists of the following stages:</p>
<ul>
<li><a class="el" href="group__gzp__02__user__guide.html#address_exchange">System Address exchange</a></li>
<li><a class="el" href="group__gzp__02__user__guide.html#host_id_exchange">Host ID exchange</a></li>
<li><a class="el" href="group__gzp__02__user__guide.html#dyn_key_exchange">Dynamic Key exchange</a></li>
<li><a class="el" href="group__gzp__02__user__guide.html#enc_data_exchange">Encrypted User Data exchange</a></li>
</ul>
<p>Each of these stages are required in order to send encrypted user data from a Device to a Host. If encryption is not required, only the "System Address exchange" stage is required in order to send unencrypted data on pipes 2-5.</p>
<h3><a class="anchor" id="factory_pres"></a>
Factory preset parameters</h3>
<p>In order for pairing and key exchange to occur, an unpaired Host and Device must share the following factory preset parameters:</p>
<table  border="1" cellspacing="0">
<tr align="center">
<td>Parameter </td><td>Secret?</td><td>Bytes </td><td>Purpose </td><td>Set  </td></tr>
<tr align="center">
<td>Secret Key </td><td>Yes </td><td>16 </td><td align="left">Encrypting Host ID when sent from Device to Host</td><td>Factory preset  </td></tr>
<tr align="center">
<td>Pairing Address </td><td>No </td><td>5 </td><td align="left">Sending of System Address from Device to Host </td><td>Factory preset  </td></tr>
<tr align="center">
<td>Packet Validation ID </td><td>No </td><td>3 </td><td align="left">Authentication of packets </td><td>Factory preset  </td></tr>
</table>
<p>In addition, every Host has the following unique parameters which are generated at runtime:</p>
<table  border="1" cellspacing="0">
<tr align="center">
<td>Parameter </td><td>Secret?</td><td>Bytes </td><td>Purpose </td><td>Set  </td></tr>
<tr align="center">
<td>System Address </td><td>No </td><td>5 </td><td align="left">Address used for all transmission. <br/>
Seed for generating channel set. </td><td>Runtime. First system address request.  </td></tr>
<tr align="center">
<td>Host ID </td><td>Yes </td><td>5 </td><td align="left">Encrypting Dynamic Key when sent from Device to Host </td><td>Runtime. First Host ID request.  </td></tr>
</table>
<p>The System Address and Host ID are stored in non-volatile memory (NVM) and apply for the lifetime of the Host unless the NVM is erased.</p>
<div class="image">
<img src="gzp_factory_defaults.png" alt="gzp_factory_defaults.png"/>
<div class="caption">
Initial pairing parameters</div></div>
 <h3><a class="anchor" id="address_exchange"></a>
System Address exchange</h3>
<p>For a Device to pair with a Host it must first obtain the System Address which all subsequent key exchange and data transfer occurs on. This transaction occurs on the pipe 0 and is transmitted in cleartext on the air as it is not a secret.</p>
<div class="image">
<img src="gzp_address_exchange.png" alt="gzp_address_exchange.png"/>
<div class="caption">
System address exchange</div></div>
 <h3><a class="anchor" id="host_id_exchange"></a>
Host ID exchange</h3>
<p>Once the Device has the System Address it can request the Host ID on the pipe <a class="el" href="group__gzp__02__api.html#ga5061300f8d940942b9794fdbcb97b403">GZP_DATA_PIPE</a>. The Host ID is used to generate subsequent "dynamic keys" for encrypted data transfer.</p>
<p>After receiving a Host ID request, the Host generates the Host ID if it has not already done so. The Host ID is generated using the random Session Token received from the Device in the Host ID request as well as the session counter.</p>
<p>The Device sends a packet to fetch the Host ID and the secret Host ID is transmitted on the encrypted pipe GZP_DATA_PIPE using the shared Secret Key.</p>
<p>The following security precautions are taken for the Host ID exchange:</p>
<ul>
<li>Passive eavesdropping is prevented by using AES encryption.</li>
<li>Replay attacks are prevented by using session tokens.</li>
<li>Man-in-the-middle and malicious device attacks can be prevented by implementing a user validation stage before the Host ID is sent to the Device (discussed in the next section).</li>
</ul>
<div class="image">
<img src="gzp_host_id_exchange.png" alt="gzp_host_id_exchange.png"/>
<div class="caption">
Host ID exchange</div></div>
<p> The Host ID can be compromised it the attacker has knowledge of the Secret Key. The attacker could in that case eavesdrop the Host ID exchange and obtain the Host ID or attempt to pair as a malicious device and obtain the Host ID.</p>
<h3><a class="anchor" id="about_validation"></a>
Optional Host ID validation stage</h3>
<p>Before the Host ID is sent from the Host to the Device, it is possible for the application to add an additional validation stage. This validation stage would typically contain some kind of user intervention, for example that the user is requested to write a keycode on the Device, displayed on a screen on the Host.</p>
<p>This requires the Device to be able to send user data before all parameters normally used for encrypting user data have been exchanged. Nevertheless, it is still possible to send encrypted data during the validation stage. This data will be encrypted in the same fashion as normal user data, described in <a class="el" href="group__gzp__02__user__guide.html#enc_data_exchange">Encrypted User Data exchange</a>, except for the following differences:</p>
<ul>
<li>The Secret Key will be used instead of the Dynamic Key.</li>
<li>Session token update will not be sent from the Device to the Host.</li>
</ul>
<p>As the same session token is used throughout the entire validation stage, the data exchange in the validation stage will have the following properties:</p>
<ul>
<li>Only the same Device as the one initializing the Host ID exchange will be able to send data that will be accepted by the Host</li>
<li>Only the Device used for sending user data during the validation stage will be able to decrypt the Host ID sent from the Host</li>
</ul>
<h3><a class="anchor" id="dyn_key_exchange"></a>
Dynamic Key exchange</h3>
<p>The Dynamic Key is used for encrypting user data. Each Device is required to have a unique Dynamic Key, and the Host is required to know the Dynamic Key for each Device is communicates with.</p>
<p>A Device can initialize the update of the Dynamic Key at any time. The Dynamic Key is generated randomly on the Device and then communicated to the Host. The Host ID is used for encrypting the Dynamic Key.</p>
<p>The Dynamic Key is considered a secret, and the following security precautions are taken:</p>
<ul>
<li>Passive eavesdropping is prevented by using AES encryption.</li>
<li>Replay attacks prevented by using session tokens sent from Host.</li>
<li>Only Devices knowing the Host ID will be able to update the Dynamic Key in the Host.</li>
</ul>
<div class="image">
<img src="gzp_key_exchange.png" alt="gzp_key_exchange.png"/>
<div class="caption">
Dynamic Key exchange</div></div>
<p> The main reasons for using a dynamic key for encryption of user data are:</p>
<ul>
<li>A Host must be able to be paired with multiple Devices at the same time, and none of these should be using the same key for encryption of user data.</li>
<li>The solution must be able to implement on OTP devices, where storing of keys in non volatile memory during runtime is not desired.</li>
</ul>
<p>The secrecy of the Dynamic Key is dependent on the secrecy of the Host ID. The Dynamic Key can be compromised if both these conditions are met:</p>
<ul>
<li>Attacker eavesdrops the exchange of the Dynamic Key</li>
<li>The Host ID has been compromised.</li>
</ul>
<h2><a class="anchor" id="enc_data_exchange"></a>
Encrypted User Data exchange</h2>
<p>Once the Device and Host share a Dynamic key, encrypted data exchange can occur. When sending Encrypted User Data the following security precautions are being taken:</p>
<ul>
<li>Passive eavesdropping prevented by AES encryption.</li>
<li>"Hostile" Device attacks prevented as only Devices knowing the current Dynamic Key will be able to send user data that will be accepted by the Host.</li>
<li>Known plaintext/ciphertext attacks prevented by AES encryption.</li>
<li>Replay attacks prevented by using session tokens sent from Host.</li>
<li>Frequency analysis attacks prevented by updating session token for every packet.</li>
</ul>
<div class="image">
<img src="gzp_user_data_exchange.png" alt="gzp_user_data_exchange.png"/>
<div class="caption">
Encrypted user data exchange</div></div>
<p> The secrecy of the Encrypted User Data is dependent on the secrecy of the Dynamic Key. Therefore the Encrypted User Data may be compromised if both these conditions are met:</p>
<ul>
<li>Attacker eavesdrops the user data exchange.</li>
<li>The current Dynamic Key has been compromised.</li>
</ul>
<h2><a class="anchor" id="gzll_limitations"></a>
Resource Requirements</h2>
<p>As Gazell Pairing employs the Gazell Link Layer precompiled library, it requires exclusive access to the Radio peripheral as well as the Timer and software interrupt used by the Gazell Link Layer. These are specified precisely in the Gazell Link Layer documentation (see <a class="el" href="group__gzll__02__user__guide.html#gzll_resources">Resources</a> in the Gazell Link Layer documentation).</p>
<p>Gazell Pairing also employs three nRF51 peripherals:</p>
<ul>
<li>Random Number Generator, for generation of keys and tokens.</li>
<li>AES Electronic Codebook (ECB), for encryption/decryption.</li>
<li>Non-Volatile Memory Controller (NVMC), for storing of pairing parameters.</li>
</ul>
<p>In addition Gazell Pairing employs the following Gazell Link Layer resources.</p>
<ul>
<li>Two pipes: one for pairing and one for encrypted data transmission.</li>
<li>Gazell pairing determines the channel set used by Gazell.</li>
</ul>
<p>Since GZP requires exclusive access to pipes 0 and GZP_DATA_PIPE (default pipe 1), and it must control the internal Gazell Link Layer variables <b>base_address_0</b>, <b>base_address_1</b> and <b>prefix_address_byte</b> for pipes GZP_PAIRING_PIPE (always pipe 0) and GZP_DATA_PIPE (configurable). The remaining six pipes can be used freely by the main application. Note that base_address_1 applies for pipes 2-7. Gazell Pairing must also determine whether the RX pipes 0 and 1 are enabled. So care should be taken to not affect the rx_enabled status of these pipes.</p>
<p>It follows that the the following Gazell Link Layer API functions should not be accessed.</p>
<ul>
<li><a class="el" href="group__gzll__02__api.html#gada5d1b9ca90be29ebc600a977cb1ba2d" title="Set the base address for pipe 0.">nrf_gzll_set_base_address_0()</a></li>
<li><a class="el" href="group__gzll__02__api.html#gafae33f3818b7c9a64d368352e7218a08" title="Set the base address for pipes 1-7.">nrf_gzll_set_base_address_1()</a></li>
<li><a class="el" href="group__gzll__02__api.html#ga8ddb9c88340dfa0dd26a49f5a233bc14" title="Set the address prefix byte for a specific pipe.">nrf_gzll_set_address_prefix_byte()</a> (for pipes 0 and 1)</li>
<li><a class="el" href="group__gzll__02__api.html#ga7c41a4d1c773221ad106ebc67832da77" title="Set which pipes shall listen for packets in Host mode.">nrf_gzll_set_rx_pipes_enabled()</a> (can be used but the enabled status of pipes 0 and 1 should not be modified)</li>
<li><a class="el" href="group__gzll__02__api.html#ga1aa10efb06cf0cd2a5b197a4cd65deaa" title="Set the table of Radio Frequency (RF) channels.">nrf_gzll_set_channel_table()</a>.</li>
</ul>
<h2><a class="anchor" id="sysaddr_generation"></a>
System Address and Channel Table Generation</h2>
<p>Every Host generates its own unique System Address and channel table resulting in minimizing the interference between desktops.</p>
<p>The System Address also determines the Gazell channel table on the Host and Device for subsequent transactions. The System Address is generated on the Host side. On nRF24LE1 chips, the system address is randomly generated while on the nRF24LU1 chips this is generated from the chip ID in the info page. This gives a unique System Address. Both the Device and Host use the System Address to generate the same channel table.</p>
<p>When sending the System Address request, the Device knows only the lowest and highest RF channels in the Host's channel table (i.e. GZP_CHANNEL_LOW and GZP_CHANNEL_HIGH). This is sufficient for the System Address transaction as the Device and Host will eventually change channels so that can communicate. In an environment with many desktops using Gazell Pairing, the Device and Host will find another channel to communicate on.</p>
<h2><a class="anchor" id="terminology"></a>
Terminology</h2>
<p><b> Frequency analysis attacks </b></p>
<p>Frequency analysis is the study of the frequency of letters, or groups of letters, in the ciphertext. Even the most advanced ciphers such as AES, do not provide security against this type of attack unless precautions for such an attack have being taken. Frequency analysis is based on the fact that certain letters and combinations of letters occur with varying frequencies. Knowing these properties of a given language, it can be possible to decipher the packets sent from the keyboard without having to break the cipher itself.</p>
<p>The encrypted user data in Gazell pairing is protected against frequency analysis attacks by using a session token, which is incremented for every packet. This is equivalent to AES "counter" mode. As the keys can take on any value they can not be compromised by a frequency analysis attack.</p>
<p><b>"Hostile" Device attack </b></p>
<p>Here, we have defined a "hostile" Device attack as the scenario where a hostile third party Device has been able to pair with the Host and start sending data that will be interpreted as trusted user data by the Host. The hostile device may also obtain any keys shared with other devices in order to eavesdrop communications.</p>
<p>For example, having such an capability with a wireless keyboard, an attacker can easily perform a range of operations on the host PC, like damaging contents on the PC or install spy-ware or key-logging software.</p>
<p><b>Man-in-the-middle attack </b></p>
<p>The man-in-the-middle attack is a form of active eavesdropping in which the attacker makes independent connections with the victims during key exchanges and relays messages between them, making them believe that they are talking directly to each other over a private connection, when in fact the entire conversation is controlled by the attacker.</p>
<p>One method to prevent this attack is for the communicating parties have a shared secret to authenticate the source of the transmission. In Gazell pairing this is provided by the factory programmed Secret Key.</p>
<p><b>Replay attacks </b></p>
<p>A replay attack is an attack where previously sent packets are recorded by a third party and resent to the receiver.</p>
<p>Here, the third party is not actually deciphering the keyboard packets, but repeats commands previously sent to the receiver.</p>
<p>For example, a typical "log in" sequence on a PC consisting of entering a username and a password is in particular vulnerable for a replay attack.</p>
<p>In Gazell pairing, the use of dynamic keys and session tokens prevent this kind of attack.</p>
<p><b>Session token </b></p>
<p>Here, a session token is a random, or pseudo random, number used for adding randomness to encryption of data packets. The session token is not assumed as a secret.</p>
<p>The session token is generated prior to every new session and discarded after the session has ended.</p>
<p>Here, a session consists of one message being sent from a transmitter to a recipient and one message being sent in return from the recipient to the transmitter </p>
</div>
</div>
  <div id="nav-path" class="navpath">
    <ul>

    <li class="footer">
      Copyright &copy 2006-2011 <a href="http://www.nordicsemi.no" style="text-decoration:none">Nordic Semiconductor</a>.
      All Rights Reserved.
      <a href="disclaimer.html">Disclaimer</a>
    </li>
   </ul>
 </div>


</body>
</html>
